postcss-image-set-function

What is postcss-image-set-function?

The postcss-image-set-function package is a PostCSS plugin that allows you to polyfill the CSS image-set function. This function is used to specify different images to use in different situations, such as high-resolution displays or different types of devices. The plugin transforms image-set notation into a background-image declaration that is compatible with all browsers.

What are postcss-image-set-function's main functionalities?

Transform image-set function

This feature allows you to write CSS using the image-set function, which the plugin will then transform into a background-image property with corresponding -webkit-image-set for compatibility with browsers that support it.

background-image: image-set('img/test.png' 1x, 'img/test-2x.png' 2x, 'img/test-print.png' 600dpi);

Fallback for browsers without image-set support

The plugin provides a fallback for browsers that do not support the image-set function by outputting a standard background-image property with the 1x image as the default.

background-image: url('img/test.png');
background-image: image-set('img/test.png' 1x, 'img/test-2x.png' 2x);

Other packages similar to postcss-image-set-function

postcss-preset-env

postcss-preset-env is a plugin that allows you to use future CSS features today. It includes polyfills for various CSS features, including the image-set function, similar to postcss-image-set-function, but it is more comprehensive as it covers a wide range of CSS features.

postcss-assets

postcss-assets is a PostCSS plugin that helps manage project assets. It can resolve paths, inline files, and more. While it does not directly polyfill the image-set function, it can be used in conjunction with other plugins to manage images and resolutions, which is a part of what postcss-image-set-function does.

README

PostCSS image-set() Function

PostCSS image-set() Function lets you display resolution-dependent images using the image-set() function in CSS, following the CSS Images specification.

.example {
  background-image: image-set(
    url(img.png) 1x,
    url([e-mail]) 2x,
    url([e-mail]) 600dpi
  );
}

/* becomes */

.example {
  background-image: url(img.png);
}

@media (-webkit-min-device-pixel-ratio: 2), (min-resolution: 192dpi) {
  .example {
    background-image: url([e-mail]);
  }
}


@media (-webkit-min-device-pixel-ratio: 6.25), (min-resolution: 600dpi) {
  .example {
    background-image: url([e-mail]);
  }
}

.example {
  background-image: image-set(
    url(img.png) 1x,
    url([e-mail]) 2x,
    url([e-mail]) 600dpi
  );
}

Usage

Add PostCSS image-set() Function to your project:

npm install postcss-image-set-function --save-dev

Use PostCSS image-set() Function as a PostCSS plugin:

const postcss = require('postcss');
const postcssImageSetFunction = require('postcss-image-set-function');

postcss([
  postcssImageSetFunction(/* pluginOptions */)
]).process(YOUR_CSS /*, processOptions */);

PostCSS image-set() Function runs in all Node environments, with special instructions for:

Node	PostCSS CLI	Webpack	Gulp	Grunt

Options

preserve

The preserve option determines whether the original declaration using image-set() is preserved. By default, it is preserved.

postcssImageSetFunction({ preserve: false })

.example {
  background-image: image-set(
    url(img.png) 1x,
    url([e-mail]) 2x,
    url([e-mail]) 600dpi
  );
}

/* becomes */

@media (-webkit-min-device-pixel-ratio: 1), (min-resolution: 96dpi) {
  .example {
    background-image: url(img.png);
  }
}

@media (-webkit-min-device-pixel-ratio: 2), (min-resolution: 192dpi) {
  .example {
    background-image: url([e-mail]);
  }
}


@media (-webkit-min-device-pixel-ratio: 6.25), (min-resolution: 600dpi) {
  .example {
    background-image: url([e-mail]);
  }
}

onInvalid

The onInvalid option determines how invalid usage of image-set() should be handled. By default, invalid usages of image-set() are ignored. They can be configured to emit a warning with warn or throw an exception with throw.

postcssImageSetFunction({ onInvalid: 'warn' }) // warn on invalid usages

postcssImageSetFunction({ onInvalid: 'throw' }) // throw on invalid usages

Image Resolution

The image-set() function allows an author to provide multiple resolutions of an image and let the browser decide which is most appropriate in a given situation. The image-set() also never fails to choose an image; the <resolution> just helps determine which of the images is chosen.

Since this plugin is not a browser, the image options are sorted by device pixel ratio and the lowest ratio is used as the default, while the remaining images are pushed behind media queries.

Therefore, this plugin can only approximate native browser behavior. While images should typically match the resolution as the device they’re being viewed in, other factors can affect the chosen image. For example, if the user is on a slow mobile connection, the browser may prefer to select a lower-res image rather than wait for a larger, resolution-matching image to load.